home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 2 / Amiga Tools 2.iso / tools / qtools / qtlibrary / quicktools.doc next >
Text File  |  1995-03-09  |  6KB  |  253 lines
  1. TABLE OF CONTENTS
  2.  
  3. quicktools.library/FindMatchReq
  4. quicktools.library/FindNextMatch
  5. quicktools.library/FreeMatchData
  6. quicktools.library/LockQToolsData
  7. quicktools.library/SetupMatchData
  8. quicktools.library/UnLockQToolsData
  9. quicktools.library/FindMatchReq               quicktools.library/FindMatchReq
  10.  
  11.    NAME    
  12.     FindMatchReq -- Scan for matches, and show them in a requester.
  13.  
  14.    SYNOPSIS
  15.     name = FindMatchReq( match, buffer, len, tagitems )
  16.     D0                    A0     A1      D0      A2
  17.  
  18.     STRPTR FindMatchReq( STRPTR, STRPTR, ULONG, struct TagItem * );
  19.  
  20.     name = FindMatchReqTags( match, buffer, len, Tag1, ... )
  21.  
  22.     STRPTR FindMatchReqTags( STRPTR, STRPTR, ULONG, ULONG, ...);
  23.  
  24.    FUNCTION
  25.     Scans the datafile for files/dirs matching the match parameter. If 
  26.     more than one file/dir match a requester will pop up asking the user
  27.     to select. The name the user selected is returned.
  28.  
  29.    INPUTS
  30.     match - Pointer to string to find.
  31.     buffer - Buffer to hold the result.
  32.     len - Number of bytes of space in buffer.
  33.     tagitems - pointer to TagItem array.
  34.  
  35.     Here are the TagItem.ti_Tag values that are defined for
  36.     FindMatchReq().
  37.  
  38.     QT_ScanType - What to scan for. Defined values for ti_Data are:
  39.         QT_SCAN_DIRECTORY - Scan for directorys.
  40.         QT_SCAN_FILE - Scan for files.
  41.         Default scantype is QT_SCAN_FILE.
  42.  
  43.     QT_ReqTitle - Title to use in the title of the requester window is
  44.         in (STRPTR) ti_Data. Default is "Select file" for QT_SCAN_FILE 
  45.         and "Select directory" for QT_SCAN_DIRECTORY.
  46.  
  47.     QT_CenterReq - Center the requester on the screen if (BOOL) ti_Data
  48.         is TRUE. Default is TRUE.
  49.     
  50.     QT_PubScreen - Name of the public screen to open requster on is 
  51.         pointed by (STRPTR) ti_Data. Default is to open on default 
  52.         public screen. Will also fallback to the default public screen if
  53.         LockPubScreen() fails on QT_PubScreen.
  54.  
  55.    RESULT
  56.     name - Pointer to a string matching the match parameter.
  57.         If there are no match a null-pointer is returned. On failure
  58.         IoErr() contains a secondary result. If the buffer is too 
  59.         small, a null-pointer is returned and IoErr() == 
  60.         ERROR_OBJECT_WRONG_TYPE.
  61.  
  62.    EXAMPLE
  63.  
  64.    NOTES
  65.  
  66.    BUGS
  67.  
  68.    SEE ALSO
  69.  
  70. quicktools.library/FindNextMatch             quicktools.library/FindNextMatch
  71.  
  72.    NAME    
  73.     FindNextMatch -- Find next name that matches.
  74.  
  75.    SYNOPSIS
  76.     name = FindNextMatch( matchdata, buffer, len )
  77.     D0                       A0        A1     D0
  78.  
  79.     STRPTR FindNextMatch( APTR, STRPTR, ULONG );
  80.  
  81.    FUNCTION
  82.     Finds the next name that matches the match parameter used when 
  83.     calling SetupMatchData(). When there are no more matches a NULL 
  84.     pointer is returned.
  85.  
  86.    INPUTS
  87.     matchdata - Pointer returned from SetupMatchData().
  88.     buffer - Buffer to hold the result.
  89.     len - Number of bytes of space in buffer.
  90.  
  91.    RESULT
  92.     name - Pointer to a string matching the match parameter.
  93.         If there are no match a null-pointer is returned. On failure
  94.         IoErr() contains a secondary result. If the buffer is too 
  95.         small, a null-pointer is returned and IoErr() == 
  96.         ERROR_OBJECT_WRONG_TYPE.
  97.  
  98.    EXAMPLE
  99.  
  100.    NOTES
  101.  
  102.    BUGS
  103.  
  104.    SEE ALSO
  105.     SetupMatchData(), FreeMatchData()
  106.  
  107. quicktools.library/FreeMatchData             quicktools.library/FreeMatchData
  108.  
  109.    NAME    
  110.     FreeMatchData -- Free memory allocated with SetupMatchData() 
  111.  
  112.    SYNOPSIS
  113.     FreeMatchData( matchdata )
  114.                       A0
  115.  
  116.     void FreeMatchData( APTR );
  117.  
  118.    FUNCTION
  119.     Frees memory allocated with SetupMatchData() to hold matchdata 
  120.     structure and buffers. Should be called as soon as possible after 
  121.     all necesary calls to FindNextMatch() are done.
  122.  
  123.    INPUTS
  124.     matchdata - Pointer returned from SetupMatchData().
  125.  
  126.    RESULT
  127.  
  128.    EXAMPLE
  129.  
  130.    NOTES
  131.     This funtion is safe to call with a NULL pointer.
  132.  
  133.    BUGS
  134.  
  135.    SEE ALSO
  136.     SetupMatchData(), FindNextMatch()
  137.  
  138. quicktools.library/LockQToolsData           quicktools.library/LockQToolsData
  139.  
  140.    NAME    
  141.     LockQToolsData -- Lock QuickTools Data files.
  142.  
  143.    SYNOPSIS
  144.     LockQToolsData()
  145.  
  146.     void LockQToolsData( void );
  147.  
  148.    FUNCTION
  149.     Gains exclusive access to the datafiles for QuickTools. Used by 
  150.     GetQInfo when updating the datafiles. This function wil not return
  151.     until the the exlusive access is obtained.
  152.  
  153.    INPUTS
  154.  
  155.    RESULT
  156.  
  157.    EXAMPLE
  158.  
  159.    NOTES
  160.     After calling LockQToolsData(), UnLockQToolsData() *must* be called 
  161.     before using any of the other funtions in the library. 
  162.  
  163.     Do *not* call this function if you have any allocated matchdata. 
  164.     Let's repeat it: Free *all* your matchdata *before* calling this
  165.     function.
  166.  
  167.     This function is provided so extern programs can update the datafiles
  168.     without worring about other tasks pokeing around with the datafiles.
  169.  
  170.    BUGS
  171.  
  172.    SEE ALSO
  173.     UnLockQToolsData()
  174.  
  175. quicktools.library/SetupMatchData           quicktools.library/SetupMatchData
  176.  
  177.    NAME    
  178.     SetupMatchData -- Setup buffers and initialize matchdata structure.
  179.  
  180.    SYNOPSIS
  181.     matchdata = SetupMatchData( match, tagitems )
  182.     D0                           A0       A1
  183.  
  184.     APTR SetupMatchData( STRPTR, struct TagItem * );
  185.  
  186.     matchdata = SetupMatchDataTags( match, Tag1, ... )
  187.  
  188.     APTR SetupMatchDataTags(STRPTR, ULONG, ... );
  189.  
  190.    FUNCTION
  191.     Sets up buffers and initilaizes a matchdata structure to be used in 
  192.     the following calls to FindNextMatch().
  193.  
  194.    INPUTS
  195.     match - Pointer to string to find.
  196.     tagitems - pointer to TagItem array.
  197.  
  198.     Here are the TagItem.ti_Tag values that are defined for
  199.     SetupMatchData().
  200.  
  201.     QT_ScanType - What to scan for. Defined values for ti_Data are:
  202.         QT_SCAN_DIRECTORY - Scan for directorys.
  203.         QT_SCAN_FILE - Scan for files.
  204.         Default scantype is QT_SCAN_FILE.
  205.  
  206.     QT_ExactLastPart - Don't add '#?' to the last part of the given 
  207.         match if (BOOL) ti_Data is TRUE. 
  208.  
  209.     QT_ExactMatch - Don't add any '#?' to the given match if (BOOL) 
  210.         ti_Data is TRUE.
  211.  
  212.    RESULT
  213.     matchdata - Pointer to a machdata structure to be used when calling
  214.         FindNextMatch() and FreeMatchData(). On failure a NULL pointer
  215.         is returned, and a secondary result can be found in IoErr().
  216.  
  217.    EXAMPLE
  218.  
  219.    NOTES
  220.  
  221.    BUGS
  222.  
  223.    SEE ALSO
  224.     FindNextMatch(), FreeMatchData()
  225.  
  226. quicktools.library/UnLockQToolsData       quicktools.library/UnLockQToolsData
  227.  
  228.    NAME    
  229.     UnLockQToolsData -- UnLock QuickTools Data files.
  230.  
  231.    SYNOPSIS
  232.     UnLockQToolsData()
  233.  
  234.     void UnLockQToolsData( void );
  235.  
  236.    FUNCTION
  237.     Frees the exclusive access to the datafiles gained by 
  238.     LockQToolsData(). This function also flushes the internal buffers. 
  239.  
  240.    INPUTS
  241.  
  242.    RESULT
  243.  
  244.    EXAMPLE
  245.  
  246.    NOTES
  247.  
  248.    BUGS
  249.  
  250.    SEE ALSO
  251.     LockQToolsData()
  252.  
  253.